Debugging (IM: XO)

Inside Macintosh: QuickDraw GX Objects /: Chapter 1 - Introduction to QuickDraw GX / The QuickDraw GX Programming Environment

Debugging
QuickDraw GX provides both a debugging and non-debugging version of the software. In addition, QuickDraw GX provides a low-level debugger, similar to MacsBug, that allows you to examine internal data structures. This section summarizes these approaches to debugging. For more information, see the debugging chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

Debugging and Non-Debugging Versions
There are two versions of QuickDraw GX. The debugging version is intended for application development and is meant for use by software developers only. The non-debugging version is intended for running completed applications and is the publicly released version of QuickDraw GX.
The debugging version of QuickDraw GX provides extensive error handling. It posts all three levels of diagnostic messages (errors, warnings, and notices), and it provides special functions to assist in the posting, utilization, and control of debugging messages. The debugging version allows you to perform validation checking on both QuickDraw GX objects and your own application parameters at each function call.
The debugging version also includes the GXGetShapeDrawError function, which can give you very specific information on why a particular shape may not have drawn correctly.
The non-debugging version of QuickDraw GX has much less extensive error handling. It reports only two levels of result messages (errors and warnings), and only a limited number of them. In the non-debugging version, errors and warnings are mostly limited to out-of-memory and range-checking messages.

Debugging With GraphicsBug
GraphicsBug is a tool you can use to track down bugs in a QuickDraw GX application. Its mode of use and its command set are analogous to MacsBug. GraphicsBug works with both the debugging and non-debugging versions of QuickDraw GX.
You can use GraphicsBug to check the contents of QuickDraw GX memory and to display and validate objects within memory. GraphicsBug does not allow you to create, modify, or dispose of objects. Listing 1-1 shows a sample dump of the QuickDraw GX heap created with GraphicsBug.
Listing 1-1 Sample GraphicsBug heap dump (HD) listing
 Start   Length   Æ     Typ Busy Mstr Ptr Temp TBsy Disk  Object
00469728 0000010c+00    d        00000000       b        heap header block
00469834 0000003c+00    d        00000000                freeFileList
00469870 0000005c+00    i        00470e68                text
004698cc 00000042+02    i        00470e64                text
00469910 000000a0+00    i        00470e60                style
004699b0 00000036+02    i        00470e5c                ink
004699e8 00000060+00    i        00470e58                transform
00469a48 000000c0+00    d        00000000                port
00469b08 00000038+00    i        00470e54                full
00469b40 00007228       f        00000000                free block
00470d68 00000110+00    d        00469728       b        master pointer block
00470e78 0000000c+00    d        00469728       b        heap trailer block

          Total Blocks    Total of Block Sizes
Free      0001  #     1    00007228    #    29224
Direct    0002  #     2    00000318    #      792
Indirect  0006  #     6    00000210    #      528
Sub Heaps 0000  #     0    00000000    #        0
Heap Size 0009  #     9    0000775c    #    30556
The listing shows the objects that you create as well as private QuickDraw GX objects. From the heap dump, you can look into the contents of these objects using additional GraphicsBug commands. For a complete list of commands, type ? on the GraphicsBug command line.

Note
Do not use GraphicsBug to make assumptions about the structure of objects in memory; object structure is subject to change.
For examples of the use of GraphicsBug in analyzing flattened shapes, see the stream format chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.